@emailmaker/emailmaker 1.1.108 → 1.2.0

package/README.md

@@ -555,6 +555,7 @@ HTML-разметка письма.
 | nextButtonText                         | Текст на второстепенной кнопке.                                             | ''                    |
 | saveButtonEnabled                      | Показ основной кнопки.                                                      | true                  |
 | saveButtonText                         | Текст основной кнопки.                                                      | ''                    |
+| saveHotkeyEnabled                      | Сохранение по Ctrl+S / Cmd+S. `false` отключает его; диалог браузера «Сохранить страницу» всё равно не открывается. | true |
 | commandButtonsEnabled                  | Показ основной и второстепенной кнопки.                                     | true                  |
 |                                        |                                                                             |                       |
 | sidePanelFloating                      | Плавающая боковая панель.                                                   | true                  |
@@ -771,7 +772,8 @@ emailmaker.init({
 | handleShareEmail | Поделиться. |
 | handleLivePreviewEmail | Живой предпросмотр. |
 | handlePreviewEmail | Предпросмотр. |
-| handleValidate | Результат проверки кода (**`CodeError[]`**). |
+| handleValidate | Ошибки редактора кода (**`CodeError[]`**) — то, что он подчёркивает. Приходит после проверки текста в редакторе: пока ошибки есть — на каждую правку, и один раз, когда они исчезли; если ошибок не было и нет — не приходит. Только после того, как режим кода хоть раз открывали. Проверить письмо по требованию — **`validateCode()`**. |
+| handleImportValidate | Ошибки разметки импортируемого файла (**`{ errors: CodeError[], fileName }`**), найденные до разбора браузером: браузер молча «чинит» сбитую разметку, и редактор ошибок уже не увидит. Файл проверяется, только если на событие есть подписчики. Импорт событие не задерживает и не отменяет; у чистого файла **`errors`** пустой. |
 | handleTestEmailSend | Отправка тестового письма. |
 | handleTestEmailModal | Открыто окно тестовой отправки. |
 | handleDestroy | Перед уничтожением экземпляра. |
@@ -783,9 +785,60 @@ emailmaker.init({
 | handleReadLocale | Язык интерфейса (**`AppConfigMixin`**). Каталог возвращается текстом **`.po`**, JSON-строкой или готовым объектом **`LocaleData`**. |
 | handleTranslate | Пользовательский перевод строк. |
 | handleLimitUsage | Отображение квот / лимитов. |
+| handleAnalyticsEvent | Действие пользователя в редакторе — для вашей аналитики; см. ниже. |
 
 Полный перечень и сигнатуры — в **`emailmaker.d.ts`** (**`ExportedApi.DataMixin.Events`** и смежные миксины).
 
+#### Аналитика: `handleAnalyticsEvent`
+
+Редактор сообщает о действиях пользователя — для вашей аналитики (Amplitude, GA и т. п.). Событие —
+**`{ name, properties }`**:
+
+- **`name`** — имя вида `editor_<объект>_<действие>`: `editor_email_saved`, `editor_layout_convert_succeeded`;
+- **`properties`** — только закрытые списки значений, числа и флажки. Идентификаторов, имён, текста
+  письма и адресов в событиях нет. Связать событие со своим письмом или пользователем — ваша часть:
+  добавьте свой идентификатор при передаче в аналитику.
+
+Обработчик не ждут: его результат не используется, исключение в нём на редактор не влияет. События
+приходят независимо от **`pushToGTM`**. Частые события — правка настройки элемента, ширина холста —
+приходят одним, после паузы.
+
+```javascript
+emailmaker.init({
+  element: '#editor',
+  content: { email: { id: '1' } },
+  getAuthToken,
+  handleAnalyticsEvent: ({ name, properties }) => {
+    amplitude.track(name, { ...properties, letter_id: currentLetterId });
+  },
+});
+```
+
+Конвертация чужой вёрстки (BeeFree, Stripo и прочей):
+
+| Событие | Когда | Свойства |
+| --- | --- | --- |
+| `editor_layout_convert_offered` | Показано предложение сконвертировать | `source`, `trigger` |
+| `editor_layout_convert_declined` | Предложение отклонено | `source`, `trigger`, `never_suggest` |
+| `editor_layout_convert_started` | Начата попытка | `source`, `method`, `trigger` |
+| `editor_layout_convert_succeeded` | Результат в редакторе | `source`, `method`, `trigger`, `duration_ms`, `fallback_to_ai` |
+| `editor_layout_convert_failed` | Попытка не удалась | `source`, `method`, `trigger`, `duration_ms`, `error_code` |
+
+`source` — `beefree` / `stripo` / `unknown`; `method` — `algorithm` / `ai`; `trigger` — `prompt` (предложение
+при открытии письма), `import`, `menu`, `retry`.
+
+Остальные события:
+
+| Область | События |
+| --- | --- |
+| Письмо и блок | `editor_email_saved`, `editor_block_saved`, `editor_back_clicked`, `editor_email_deleted`, `editor_email_delete_clicked`, `editor_email_delete_modal_opened`, `editor_email_duplicate_clicked`, `editor_email_duplicated`, `editor_email_import_clicked`, `editor_email_imported`, `editor_email_exported`, `editor_email_locked`, `editor_email_unlocked`, `editor_block_locked`, `editor_block_unlocked` |
+| Холст и панели | `editor_element_added`, `editor_element_setting_changed`, `editor_canvas_resized`, `editor_pane_tab_opened`, `editor_config_mode_changed`, `editor_mode_changed`, `editor_code_mode_activated`, `editor_breadcrumb_clicked` |
+| Проверки и предпросмотр | `editor_code_checked`, `editor_links_checked`, `editor_images_checked`, `editor_spam_checked`, `editor_preview_opened`, `editor_test_email_modal_opened`, `editor_test_email_sent`, `editor_email_shared`, `editor_inbox_tests_opened`, `editor_version_history_opened`, `editor_web_version_opened` |
+| ИИ и обсуждение | `editor_ai_message_sent`, `editor_ai_reply_received`, `editor_ai_role_selected`, `editor_ai_subject_inserted`, `editor_ai_preheader_inserted`, `editor_comment_sent`, `editor_ai_image_generation_started` |
+
+Свойства каждого события и их значения — в **`emailmaker.d.ts`**, **`ExportedApi.DataMixin.AnalyticsEventMap`**.
+Событие приходит, только если соответствующая функция включена в конфигурации.
+
 #### Восстановление автосохранения
 
 - Восстановленное содержимое редактор считает текущим: событий правки (**`handleEmailChanged`**, **`handleHtmlChanged`**) не будет, пока пользователь не изменит письмо. Автосохранение при этом остаётся у вас, поэтому при следующем открытии письмо восстановится снова.